> !FontEd.!Help version 0.27

The Font Editor
--------------

The Font Editor can be invoked by double-clicking either on the Editor
application itself or on a Font outline, bitmap or metrics file.

Outline files contain the device-independent form of a font, as a series of
straight lines and bezier curves, which when filled at an appropriate scale
factor using the Draw module will draw the required characters.  This
technique is used by the new Font Manager, which caches the resulting
bitmaps in order to speed up the process of painting the fonts.

Bitmap files contain a single size of a font, produced on request by the
editor from a master outline font file.  The bitmaps are computed by drawing
the outline font at the appropriate size into a set of bitmaps, which can
then be manually 'tweaked' using the editor if desired before being
compacted using a form of run-length encoding.

Note that if no manual tweaking is performed, the only advantage of
producing bitmap files is to speed up the process of font cacheing, since
the Font Manager can itself perform the conversion from outline to bitmap
fonts 'on the fly', as it reads in the font.

In order to improve the appearance of the bitmap fonts, a set of 'scaffold
lines' can be defined along with the character outlines, to which line
endpoints can be linked.  The purpose of these scaffold lines is to allow
'grid constraints' to be enforced when an outline character is converted to
a bitmap form, using a technique based on an article in Siggraph '88 called
'Character Generation Under Grid Constraints' by Roger D. Hersch of the
Swiss Federal Institute of Technology in Lausanne.

The basic idea is to shift the positions of various parts of the character
so that they line up in a consistent way with the pixel grid, so that
horizontal and vertical lines of the same width will be drawn the same
width, rather than having a variation of one pixel due to grid alignment
problems.  By creating a scaffold line which lines up with the horizontal or
vertical section and linking the relevant points to the line, that section
of the character will be adjusted when being converted to a bitmap so that
the ideal number of pixel centres fall within the line.

Apart from the 'normal' scaffold lines described above, there are two other
kinds of scaffold lines known as L- and R-tangent lines, which are used to
ensure that arcs positioned so as to avoid the drawing of 'pips' or long
runs of horizontal or vertical pixels at the edges.  An L-tangent line
should be linked to an arc which bulges out to the left, while an R-tangent
line should be used for arcs bulging out to the right.  For arcs in the
Y-plane, U- and D-tangent lines deal with arcs that bulge up or down
respectively.

The scaffolding mechanism is described in greater detail in a paper which is
available separately from Acorn - since it requires various diagrams, it
cannot adequately be reproduced here.  If you are not familiar with Roger
Hersch's article, I would recommend that you read this paper before
continuing.

The rest of this document deals with the various user interfaces to the
editor - note that the Font Editor now supports interactive help, which is
often easier to understand than a document.

To use interactive help, double click on the !Help application and then
watch the help text as you move the mouse over the font editor's windows.


The Iconbar icon
----------------

Click SELECT on the IconBar icon to create a new (blank) font index window.

Click MENU to obtain the menu, which has an info box and a 'Quit' option.

Alternatively double-click on a font file or drag it onto the iconbar icon
to edit it.

When a font file (outlines or bitmaps) is loaded, a file called "IntMetrics"
is searched for in the same directory as the font file - if found, it is
loaded as the metrics file for the font.

When a font file is loaded, it is automatically checked for conformance with
the font file format, and if it does not correspond, a suitable error
message is generated and the file is not loaded.  If required, the checking
step can be omitted by holding down the control key as the file is loaded. 
This checking facility makes the font editor useful for verifying that fonts
generated by other means are valid.


The Font Index window
---------------------

When a font is loaded, a 'Font Index' window appears, which contains the
name of the font, and whether it is an outline or bitmap font.  For bitmap
fonts, the point size and device resolution is displayed.

Characters which are defined will be displayed in black, while those with no
definition are displayed in grey.  The index will then start to fill up with
the actual shapes of the characters - this process is done in the
'background', so that you can immediately start editing any of the
characters if you wish, without having to wait for it to be displayed.

For outline fonts:

  Double-clicking SELECT on a character will display its 'Skeleton' window,
  containing the outline of the character and its scaffold lines.

  Double-clicking ADJUST on a character will display its 'full' window,
  which shows what the character would look like at a particular size.  This
  size depends on the height of the window, so by dragging the size box you
  can see immediately what the character will look like at a given size.

  Dragging a character with SELECT onto another character box will copy the
  first character's definition into the other's, overwriting it.  If you
  drag a character from the font index window onto Draw or a directory
  window, the character outline is converted to a DrawFile object.

  Dragging a character with ADJUST onto another character box, or onto its
  skeleton window, will cause the destination character to use the source
  character as the 'base' character for its scaffold lines.  Each scaffold
  line in a character has a unique index in the range 1..7, and any scaffold
  lines in the source character which have no equivalent line in the
  destination character will be inherited by it.  Note that such lines are
  actually equivalent, rather than being copies - if either line is moved,
  the other will be affected.  Note that the destination character can
  subsequently acquire new lines in addition to or instead of lines in the
  source, but that new lines added in the source character will not appear
  in the destination unless the 'add global line' facility is used, or the
  source character is again dragged onto the destination.

  Dragging a character with SELECT into any Skeleton window will cause the
  character's outline to be displayed in grey as a 'template' in the window -
  this allows different characters to be compared.

  Dragging a character with SHIFT-select into another character box or
  skeleton window will import that character as a composite character
  segment.  This segment is a direct link to the original character, and
  so the use of composite sections can dramatically reduce the memory
  requirements of a font.  For example, to create a Udieresis (U umlaut):

        double-click on the Udieresis box to create a null character
        shift-drag the U onto the Udieresis box
        shift-drag the dieresis onto the Udieresis box

  It is also possible (and often necessary) to adjust the position of a
  composite section after it has been imported.  See the section about the
  Skeleton window for further details.  Note that any changes subsequently
  made to the included character will affect the character in which it is
  included, so you should be sure to get the character right before you
  include it in another one.

  Note that when a character is imported into another in this way, only the
  'local' section of the character is imported - any composite sections in
  the first character are not imported.  This allows, for example, the
  accented lower-case i's to be constructed without the need for a separate
  dotless i, since the first accented i can be produced with a local dotless
  section and an imported accent, and this character can then be included in
  the others to produce further dotless i sections.

  Dragging a character with CTRL-select onto another character that already
  contains that character as a composite section will cause the composite
  section to be removed.

For bitmap fonts:

  Double-clicking SELECT on a character will open its 'Bitmap window',
  showing an enlarged view of the characters definition, with the original
  outline displayed on top if available (see below).

Outline font menu:

  Redisplay - causes the font to be rescanned, so that all characters will
  be recomputed to suit the curent screen mode's resolution.  For example, if
  you loaded a font while in mode 12, then changed to mode 20, the characters
  in the font index would still be displayed at the old resolution.  By
  selecting 'Redisplay', you could force the Font Editor to make the
  characters look better.

  Show tree - displays a tree of the character definitions, showing which
  characters inherit scaffold lines from which others.  The characters on
  the left are the 'parents' of the characters connected to the right of
  them.  When a scaffold line is selected in a skeleton window all
  characters which contain that line are displayed in red, both in the tree
  and any relevant font index windows (including bitmap fonts which depend
  on that outline font).

  Alter - allows various aspects of the font file to be altered:

        Font name - note that in a finished font, the font name must
        correspond with the directory (relative to Font$Prefix) in which it
        resides.  Also note that the font name displayed in the window
        reflects that in the Outlines file, not the IntMetrics file.  If the
        metrics of the font are saved, the IntMetrics file will have this
        font name written into it, and it is this file which must contain
        the correct font name (to get the Font Manager to cache the font
        correctly).

        Design size - this number reflects the number of "design units" that
        correspond to 1 "em".  For example, if D is the design size of a
        font, and this is then rendered at 12 point, then the outlines will
        be scaled so that D design units equals 12 points.  Note that
        coordinates are 12 bit sign-extended, so they must be in the range
        -2048 to 2047, and must be integers.  A suitable value for the
        design size is about 500.  If the design size of a font is made
        smaller, the characters will be rendered larger for a given point
        size, while if the design size is increased, the characters will be
        rendered smaller for a given point size.

        Skeleton - this number is the threshold pixel size below which
        skeleton lines will be drawn - above this they are ignored.  See
        below for an explanation of what skeleton lines are.  The "pixel
        size" of a font at a given size is the number of pixels per em, eg.
        for a 12 point font rendered on a device with a resolution of 90
        dots per inch the pixels per em is 12 * 90 / 72 (since there are 72
        points per inch).

        Format - this controls the format of the font file.  You should
        always use version 6, since version 7 cannot be understood by the
        current font manager.

  Save - clicking on Save will save the font and its metrics (if any) under
  its old name, or alternatively you can click on Save=>Outlines or
  Save=>Metrics to save only that file, or you can edit either filename and
  press RETURN or drag the file into a directory.

  Make bitmap - you can select the settings of point size and dots per inch
  by typing into the writeable fields - SHIFT-cursor moves between fields, or
  RETURN moves you to the next one and activates the operation if you are
  already in the last field.  A new Font Index window will appear for the
  bitmap font, which will start to fill up as the characters are computed from
  the outlines.

  Debug - this is for debugging purposes and should not be used.

Bitmap font menu:

  Save - allows the font file to be saved.  Note that this option is greyed
  out if the outline font has not yet been turned into bitmaps (this is done
  in the background), since the file data depends on the bitmap information.


The Skeleton window
-------------------

The skeleton window shows a character's outline definition, including
endpoints of lines and any scaffold lines.  It can also show the outline of
one other character as a 'template', if you drag the relevant character from
its font index window into the skeleton window (see above).

Note that when editing the contents of the skeleton window (either the
character outline or any scaffold lines), any other windows which depend on
the skeleton (eg. Full char windows or bitmaps) will be automatically
updated as well.  In particular, this means that if a bitmap has been
hand-tuned since it ws computed from its outline, altering the outline will
cause the bitmap to be recomputed, overwriting the hand-tuning.

The character outline is converted to a bitmap by filling all closed
subpaths using the Draw module (with even-odd window number rule, filling
interior and interior boundary pixels), and thin-stroking all open subpaths
(known as skeleton lines). In the 'Full char' window, the thin-stroking is
drawn first in red, and the filling is done over the top in black, so that
it is immediately apperent when the thin-stroking makes any difference to
the appearance.  The idea is that for diagonal lines and thin curves, the
thin-stroking acts as a kind of 'insurance' against the line disappearing
altogether at small sizes - one should put an open subpath down the centre
of the line.  The font has a threshold pixel size above which the open
subpaths are ignored completely, since they are likely to have no effect at
large sizes.  This threshold can be changed using the menu option
Alter=>Skeleton.

While no scaffold lines are selected:

  Clicking SELECT or ADJUST on a line segment selects that line, deselecting
  any other.  The line is displayed in light blue, with the control points
  displayed in red.

  Clicking SELECT not on a line deselects any selected line.  If there are
  more than one included composite section, this also selects the next one
  in the list.  This means that you can use the cursor keys to move that
  section around within the character.

  Dragging SELECT creates a new straight line segment: if the mouse was
  originally over another point, the line segment is connected to it, and if
  this was already a 2-node, the new line is linked in between the point and
  the selected line (so you can choose which side of the point to insert the
  line).

  Dragging ADJUST over a point moves that point.  For a Bezier curve, dragging
  an endpoint moves both control points which are attached to that point by
  the same amount, thus preserving the angle of the tangent, while dragging
  either 'control point' of a straight line segment converts it to a Bezier
  curve.

  When dragging a point using SELECT or ADJUST, when the point is released,
  the Font Editor checks to see if the point is sufficiently close to an
  endpoint - if it is, and the endpoint is a 1-node, then it connects the
  dragged point precisely to the other one, and 'beeps' to show that it has
  done it.  This has one important side-effect when drawing open subpaths
  which are to act as thin-stroked 'skeletons' - for example, when doing the
  skeleton for an 'O'.  The problem is that one wants the first point in the
  path to coincide with the last, without actually being connected to it.  The
  solution is to proceed normally, allowing the Font Editor to connect the
  first and last points together.  You can then press and release SELECT on
  the final point, holding it down long enough to register as a drag
  operation.  This will cause a zero-length straight line to be inserted
  between the first and last points in the skeleton - since it is also
  selected, one can now select 'Delete' from the menu (see below) to remove
  the line and achieve the desired open subpath.

Clicking on a scaffold line's control point selects that line:

  When a scaffold line is selected, all characters which contain that line
  are displayed in red in the Font Index window.  This provides a quick check
  as to which characters would be affected by moving the line.

  In the skeleton window, any points connected to that line are displayed in
  red.  You can connect more points to the line by clicking on them using
  SELECT, or by dragging a rectangle over a group of points and releasing
  it.  Note that Bezier curve control points are always linked to the same
  scaffold line as their nearest endpoint, and that any endpoint is linked to
  one X-scaffold and one Y-scaffold line (line 0 is the null line, see
  'Disconnect' below).

  You can also link any other scaffold line to the selected one by pressing
  SHIFT-select on its control blob.  When rendering the character, this
  causes the position of the linked line to be adjusted by the movement
  caused by the selected line, before the movement of the linked line is
  itself computed.  Any lines linked to the selected line have their control
  blobs displayed in red, and if the selected line is linked to another
  line, that line's control blobs are displayed in dark green, as opposed to
  light green.

  Typically one would use this feature on character baselines, where the
  straight-bottomed and curve-bottomed characters are linked to different grid
  lines, but one of the grid lines is linked to the other, to ensure that they
  move in a consistent manner.  One would normally also link the upper serif
  line of a font to the baseline serif line, so that the height of the font
  is kept close to the ideal value.

  Pressing CTRL-select on a scaffold line links it linearly between the
  selected scaffold line and its parent.  For example, for a captital 'E',
  one would first link the top stem H-scaffold line to the bottom stem
  H-scaffold line, and would then select the top stem scaffold line and
  click CTRL-select on the middle stem H-scaffold line to link it linearly
  between the other two.  When the character is rendered, the top and bottom
  stems are first adjusted to fit the grid, and then the middle line is
  adjusted to restore the original proportions of the sections above and
  below this line before that line is itself fitted to the grid.  This
  ensures that if the upper portion of the 'E' is meant to be slightly
  smaller than the lower section, the final bitmap character will always
  have the upper section smaller than or equal to the lower section.

  You can drag any scaffold line using the SELECT or ADJUST buttons - any
  other characters containing a reference to the line are also affected.

  Clicking SELECT on the window background will only deselect the scaffold
  line if SHIFT is pressed (this is to allow SELECT-drag to drag a rectangle
  over a set of points without deselecting the scaffold line).  Pressing
  Escape will also deselect any selected scaffold line.

Skeleton menu:

  Delete - deletes the selected line (straight line or Bezier curve) or
  scaffold line, depending on which is selected at the time - note that
  selecting a scaffold line automatically deselects any selected line.

  Straighten - straightens the selected Bezier curve, if any (ie. turns it
  back into a straight line segment).

  Scaffold - various options dealing with scaffold lines, listed under
  'Scaffold menu' below.

  Display - the submenu allows various artifacts in the skeleton window
  to be displayed or not as required:

        Pointer - if not ticked, the pointer is removed whenever a drag
        commences, and is restored afterwards.

        Coords - if ticked, the coordinates of a point (in design units)
        are displayed as it is dragged.

        Width - if ticked, the character's origin and width are displayed. 
        If no metrics file is loaded, all characters have width 0 (the
        origin is displayed as a cross).

        Char BBox - if ticked, the character's current bounding box is
        displayed in red.

        Orig BBox - if ticked, the character's "original" bounding box (ie.
        that specified by the metrics file) is displayed.  This does not
        change if the character is edited - only if the metrics file is
        reloaded.

        Font BBox - if ticked, the font bounding box is displayed, with two
        horizontal lines showing the height of one em (in design units, the
        distance between these two lines is the design size of the font). 
        Note that the font bbox is not updated until the font is saved or
        reloaded.

        Bitmap - if ticked, then any bitmap dragged into the skeleton window
        will be displayed at its current scaling and orientation.  Normally
        the bitmap would be made invisible to allow the outline to be
        inspected.

        Handles - if ticked, then if there is a bitmap in this window then a
        red box will be drawn round it with 8 'handles' to allow its size
        and orientation to be altered.  Note that if the handles are
        displayed, dragging SELECT inside the area covered by the bitmap
        will cause it to be moved - to draw lines over the bitmap, the
        handles must be made invisible.

  Full char - this allows another way of getting hold of the 'full char'
  window, instead of double-clicking ADJUST on the Font Index window.

  Zoom - this allows the size of the character display to be changed.  If
  the 'variable' box is ticked, then the displayed chacter size depends on
  the height of the window, otherwise the numbers in the writeable fields
  determine the scale factors.  In multisync or VGA modes (modes 20 and 27),
  a ratio of 2:1 gives an exact corespondence between design units and
  pixels on the screen (useful when lining up scaffold lines).

Scaffold menu:

  New local - this allows a new local scaffold line to be created, subject
  to the restriction that any one character can have at most 7 vertical and
  7 horizontal lines.  The line will only exist in the current character,
  but if an ADJUST drag operation is subsequently made which causes
  another character to use this character as a base, the line will be
  inherited by the new character.

  New global - this is similar to the previous operation, except that the
  new line is propagated along all  children of the character (ie. all those
  which use it as a base, and all their children) immediately inherit the
  line.  This operation is only allowed if a line index can be found which is
  free in the current character and all its children.

  Replace - if a scaffold line is selected, this operation can be used to
  override it with a new local line.  Any children of the character which
  contained the old line will have it replaced by the new line.

  The above three options share the same submenu, which is used to select
  the type of scaffold line required.  These options will be shaded if the
  appropriate line type cannot be selected, eg. if there are no more
  scaffold lines allowed in that direction, or if you are trying to replace
  a line you can only replace it with one in the same direction (X or Y).

        H-scaffold      for horizontal stems (eg. middle of 'A')
        U-tangent       for upward-facing arcs (eg. top of 'C')
        D-tangent       for downward-facing arcs (eg. bottom of 'U')
        V-scaffold      for vertical stems (eg. left of 'b')
        L-tangent       for left-facing arcs (eg. left of 'C')
        R-tangent       for right-facing arcs (eg. right of 'D')

  Undelete - this option is used to restore a line from a parent character
  in its child if that line has been deleted or replaced in the child.  To
  use it, you should select the line in the parent that you want to put back
  in the child, then click MENU in the child and choose Scaffold=>Undelete. 
  If the line had been replaced by another line in the child, this will be
  replaced by the parent line, including any inheritances of that line in
  children of the child(!).

  Disconnect - if there is a selected scaffold line, this will attach all
  points currently connected to the selected line to line 0 (ie. no line).
  Note that this only affects the scaffolding in the direction of the selected
  line, so if an H/U/D-scaffold line was selected, the V/L/R-scaffold
  connections of the points would be unaffected.

Skeleton keys (sic):

  When the mouse is clicked in a skeleton window, it grabs the caret (its
  window border lights up), wich allows various keyboard speedups to
  operate:

    f9              is equivalent to 'Scaffold=>Disconnect' on the menu

    Escape          deselects the current line / scaffold line

    cursor keys     while dragging, move the pointer by one pixel.

    cursor keys     while not dragging, and a scaffold line is selected, all
                    points connected to that line are moved by 1 design unit
                    in the appropriate direction.

    cursor keys     while not dragging, and no scaffold line is selected,
                    and there is a composite character segment, this segment
                    will be moved by 1 design units in the appropriate
                    direction.  If there is more than one composite section,
                    clicking SELECT in the window will select the next
                    section for movement.

    SHIFT-cursor    as for cursor keys, but move by 4 design units

    CTRL-cursor     as for cursor keys, but move by 16 design units


Bitmap window
-------------

Clicking or dragging SELECT in the bitmap will set the pixel under the mouse
pointer to black.

Clicking or dragging ADJUST in the bitmap will clear the pixel under the
mouse pointer to white.

Bitmap menu:

  Rectangles - if this is ticked, a rectangular grid will be displayed over
  the character.  Selecting this option toggles the state.

  Diamonds - if this is ticked, a diamond grid will be displayed over the
  character.  This is useful when assessing whether a pixel will be filled by
  the 'thin stroke' parts of the character outline, since the stroking
  algorithm will fill a pixel if the line goes through the diamond shape
  inscribed in the pixel.

  Flatness - the flatness parameter passed to the draw module when making
  the bitmap can be altered using this option.  If 'flatness' is ticked, the
  character outline displayed over the top of the bitmap will be tweaked to
  show how the path was actually flattened by the Draw module, and how the
  scaffolding has affected the outline.

  Origin - this can be used to alter the position of the character origin
  within the pixel grid, and should not normally be used (it is for
  experimentation purposes).

Note that if the outline font that this bitmap font is derived from is
loaded in the editor, the outlines will be displayed over the bitmaps, and
the effect of altering scaffold lines or outlines will be reflected
immediately in the bitmap windows.  This is a very good way of seeing how
the scaffolding process works.

